fix(agent-sdk): show local command replies whose response never streamed - #444

Summary

• Claude Code answers a command it runs locally (/rename, /color, /usage, ...) with one complete top-level assistant message, and that message's API response never streams. The bridge now records the response ID of the last top-level message_start. When a completed top-level message carries a response ID that never started a stream, the bridge shows its text once.
• Streamed replies are unchanged: they are still shown from their deltas. Subagent frames, error frames and messages without a response ID stay out of the transcript.
• The rule reads only typed SDK fields (parent_tool_use_id, error, the message ID). It does not use the undeclared local_command_* fields.
• The existing check on the declared context_usage field stays. A test shows that /context Markdown is still shown even when a message has no response ID.
• Docs: one sentence in the architecture's activity section on where reply text comes from, and one line on the commands page.

Why

On main, /rename probe, /color blue and /usage run in Claude Code, but nothing appears under the command in claude-rs. The reply exists only in that unstreamed message, which the bridge drops. This is the reply half of #438.

The SDK declares SDKLocalCommandOutputMessage (system/local_command_output), and the bridge already shows it. I checked whether Claude Code uses it for these commands. On Claude Code 2.1.288, the version the pinned SDK 0.3.288 bundles, /rename, /color, /usage and /context each produced exactly one complete assistant message, zero stream events and no local_command_output message. So the declared message never carries these replies, and the unstreamed assistant message is their only carrier.

Refs #438

Validation

• Automated, on this branch (macOS 27.2, Apple Silicon, rustc 1.98.1 from nixpkgs rather than the CI toolchain):

  • cargo fmt --all -- --check, cargo fetch --locked: pass
  • cargo clippy --locked --all-targets --all-features -- -D warnings: pass. Five lints that are new in clippy 1.98 are allowed, because main fails them too: collapsible_match, manual_is_multiple_of, manual_is_variant_and, map_unwrap_or, while_let_loop.
  • cargo test --locked --all-features: pass. The serial terminal_resize run: pass.
  • agent-sdk: npm run build, test, lint, knip, audit and quality:duplicates: pass. The new tests live in src/bridge/message_handlers.test.ts, so npm test runs them (see Notes). They cover:
    • a never-streamed reply shown once;
    • streamed, subagent, empty, error and uncorrelated replies not shown again;
    • a non-streaming fallback after a partial stream;
    • context usage without a response ID.

• Manual: I drove the debug binary in tmux against the Claude Code bundled with the pinned SDK (2.1.288), running /rename probe and then /color blue.

• Screen text, main:

  User
  /rename probe-baseline
  User
  /color blue
   ❯ Type a message...
  

  This branch:

  User
  /rename probe-up-replies
  Claude
  Session renamed to: probe-up-replies
  Elapsed 0.0s
  User
  /color blue
  Claude
  Session color set to: blue
  Elapsed 0.0s
   ❯ Type a message...
  

Notes

• Breaking changes: N/A
• Docs updated: docs/src/architecture.md and docs/src/commands.md.
• Behaviour change worth knowing: any complete top-level reply that never streamed is now shown. That includes the text of Claude Code's non-streaming fallback after a broken stream, which main drops. The partial deltas shown before the break stay above it; a test covers this.
• The first commit's body says "measured on 2.1.296". The behaviour is identical on 2.1.288, and the test comment now cites 2.1.288. If you squash, please drop that version from the message.
• Unrelated finding: npm test runs node --test dist/**/*.test.js under sh, where ** is a single *. As a result, dist/bridge.test.js and dist/bridge.contract.test.js never run, locally or in CI. That is 333 tests. Run by hand, the same 16 spawned-bridge tests fail on main and on this branch. Reported separately as [Bug]: npm test skips bridge.test.js and bridge.contract.test.js, where 16 tests fail #446.
• No SDK upgrade: this uses only what the pinned @anthropic-ai/claude-agent-sdk 0.3.288 already exposes.
• Governance/release impact: N/A